CD Ware Multimedia 1995 May

home *** CD-ROM | disk | FTP | other *** search

/ CD Ware Multimedia 1995 May / cd Ware (Juegos) Epimundo.iso / DOS / PRGMMING / CPP100.ZIP / MANUAL.DOC < prev next >

Wrap

Text File | 1994-11-22 | 17.3 KB | 407 lines

**************** * MANUAL.DOC * **************** This manual describes the features of CPP 'The C Programming Package'. This file also gives a list of comments and advice. 1 - LEGAL STUFF --------------- This program and all the associated files are Copyright 1993,1994 by R. NADE and M. GRANDCHAMP. This is NOT a public domain software nor a Freeware. This program is Shareware. That means you can copy it, distribute it but must not sell it. You can use it for free only for trying it. If you decide that this program is good for you, you MUST register. If you do not register, you MUST NOT use it after a trying period. See REGISTER.DOC This program is provided "as is". You use it at your own risks. The authors cannot be held responsible for any damage caused by the use of The C Programming Package. In other words, if your dog bytes you, if your computer writes your applications on its own or if your TV explodes because you use CPP that is not our fault. This program can be freely distributed by BBS, CDROM, Shareware Distributors, etc. as long as it is distributed completly. Distributors can charge a nominal fee but it must not exceed 10$ and they must warn their user that CPP is shareware and that the amount they paid is not for the authors. If you are not sure of getting all the files, please contact us. If you want to know how to get our other releases or if you find a bug or want to comment or want to see a new feature of CPP, please contact us. If you are a BBS SysOp or a Shareware Distributor and want to become a registration site, please contact us. If you create a Public Domain software, a Freeware or a Shareware with The 'C Programming Package', we would be very happy if you sent us a copy of your work. Thank You. A french version of this program is available. Contact us if you do not manage to get it. Our address is : Maxime GRANDCHAMP Flat 4D - Block G Sugarwell Court Meanwood Road LEEDS LS7 2DZ ENGLAND This address is available until June 1995. From June 1995, you will be able to reach us at this one : Maxime GRANDCHAMP 2 Rue BIR HAKEIM 59160 LOMME FRANCE 2 - PURPOSES OF CPP ------------------- This program does nothing ! This is more than 8,000 lines of C source code. This code is highly portable and is made for C beginners et C medium programmers : it will help the beginners to understand how C works and it will save time to those who already program in C by providing them a user interface and a lot of common functions such as file manager : find, save, delete, etc., configuration menu : printer, colours, sounds, tests, ... All this featuring fast pull down menu and on-line help ! All you have to do is to fill up the blanks with your own menu names and with your own help text : Just fill up an ASCII text to make a wonderful help file ! This help file will be used by your program and will be readable with an ASCII reader : you do not need HELP.DOC or MANUAL.DOC anymore ! 3 - PROGRAM FEATURES -------------------- This program was written in Borland Turbo C, with no use of an external library. The compilation model is "large". This is a text version of a wonderful interface. The Graphic version (Full VGA features) will be sent free to every register user ! This graphic version features a lot of improvements such as buttons, mouse and keyboard manager, etc. Of course the VGA version was written using only the standard libraries of Turbo C. The code is splitted in various files to help you understand how it works. You already have 7 menus totally blanks. All you have to do is to fill them up with your own applications and call the appropriate functions in the file. (Sorry we will not write your application !). You can delete useless menus, change titles, there is no limit ! 4 - USER MANUAL --------------- It is in the on-line help. Choose the last menu (Help) and get a full documentation, splitted in chapters. Each chapter deals with a menu, except the Help itself. The help will help you to understand how the program works and will provide you a full help menu. Furthermore, you can access on-line help by typing <F1> when you have choosen either a menu or just a function ! These are the same help pages as in the help menu, but they only concern the actual choice. You can move in the program by one of these three ways : - MOUSE : Just click on a menu, on a line or in a box. You can click with the left or the right button. If you click in the outside of the active window, you will go back to the previous menu. - KEYBOARD : Two ways : You type Alt + <F> for the Files menu, Alt + <H> to get the help menu, etc. or when in a menu you just type the highlighted letter or, it is your choice, you use the cursor arrows and validate with <Enter>. All the other possibilities will be told to you by the program itself. If you did not disable the sound, the program will generate lovely (?) sounds when he waits a key, an error occurs, etc. 5 - COMMENTS AND ADVICE ----------------------- This is not a programming manual, but only a listing of comments and advice to use CPP properly. You will need to use your C manual to get details on the used functions (syntax, include, ...). A.1 - USING THE SOURCE ---------------------- We advice you to create a specific directory, under your C compiler directory, for instance by typing : CD C:\TC <ENTER> MD CPP CD CPP and then copy all the files in this directory by COPY A:*.* Notice that this example assumes that your C compiler is in C:\TC and the CPP files are in A:\ A.2 - C COMPILER CONFIGURATION ------------------------------ Because of the size of the files, you need to compile it in 'LARGE' model. If you did not install your TurboC with this option you will need to re-install it. A.3 - OPENING THE PROJECT ------------------------- This manual assumes that you use 'Turbo C'. If you use another compiler, refer to your documentation. As this program is made up of several files, you need to create a project to link them together. All you have to do is : - Open the project menu (Alt-P) - Create a new project file - Adding all the C files to this project. A.4 - COMPILATION OPTIONS ------------------------- To get the 'Large' compilation model : - Go in the 'Options' menu (Alt-O) - Choose 'Compile' - Then 'Code Generation' - Then select 'Model Large' A.5 - COMPILING AND LINKING --------------------------- Now you can try to compile and link the program. - Go to the 'Compile' menu (Alt-C) - Choose the second line : MAKE EXE - And confirm A.6 - COMMON ERRORS ------------------- If you get the message 'File too large', that is because you did not selected the right compiling option. Do not forget to choose the 'Large' model. If you get the message 'Call to undefined function', be sure that you put ALL the CPP C files in your project. Be sure that in the linking menu, the Graphics library is activated. If you get another problem, please contact us. B - FILES --------- We cannot do a perfect control of the files because when a file is opened, the DOS gives it an handle number BUT this number does not change even if we close the file. So, to be able to test whether a file is opened or not, we put the handle to 0 or -1 when the file is closed. This will avoid a lot of problems. C - GLOBAL VARIABLES -------------------- In order to limit the number of global variables used in this program and to avoid using local variables which cause sometimes problems without be able to fix them, we advice you to split the global variables in two groups when you declare them : - The permament ones, that are used by all the program and that represent a configuration parameter (printer, colours, menu choice..) - The variables that are used only locally and that are available when the sub-program is over. D - ON-LINE HELP ---------------- There is a full on-line help available in this program. That allows you to get everything you need just by typing <F1> anywhere in the program. Please see in the help file, in the configuration menu, how to add help screens to the existing help file HELP.TXT and how to use the utility program provided in this menu to create from your HELP.TXT (save it before !) the HELP.FIC file which is used by the program. The purpose of the function is to cut the line feeds and the carriage returns (ASCII code 0x0d and 0x0a). The file will be 5% smaller but furthermore, it avoids a display error in the case of a file offset. For the specific help, you must respect the format : display_help("xxxxxxxx",n1,n2,n3); - "xxxxxxxx" is the name of the help. It is the one that is, in the help file, at the beginning of the line above the border. You can change the menu name without any problem but we advice you not to change the call name, otherwise you will have to modify the help file. As all this is transparent for the user, it has no interest and can cause a lot of errors. - n1 is the original offset which is a parameter passed when the file is opened. It is useless for the program to search the first help screen in the whole file. So it jumps over n1 screens and then starts the search. Notice that you can add pages without changing this value : the program takes around 1 second to search in 100 screens. So the change will be useful only if you had a lot of pages. Unless you computer is so slow that you must wait several seconds before getting the help screen. - n2 is the number of the first page you want to display. It is the number in the upper-right corner of the page. All the pages are numbered in the menu border. So you always start from 1 for a menu. This allows you to add menu lines. If the page number is 0 (zero), this means that the program does not worry about pages and displays as long as the help name matches. - n3 is the number of pages to display. Most of the time it will be 1. This does not mean just one page but you are at the end of the specific help if you are at page n2+n3. This tip allows you to put as many screens as you want as long as the page number is always the same. So you can add help screens to a function without modifying the program. If you put n2=0, then put n3=0. E - GRAPHICS DRIVER AND FONTS ----------------------------- With Turbo C when you use the graphic mode, you need to have the video drivers and the fonts in the program directory. You can forget it, your user can delete one of the files and, maybe the most important thing, it does not give your program a 'pro look'. You can do it in a more lovely way by integrating these files in the graphic library (graphics.lib) so that they will be in your program. This will increase the program size of 20 KB. You can find the information in the documentation but it can be useful to memorize a way of doing it : 1 - Go into the sub-directory where EGAVGA.BGI and *.CHR files are. 2 - Transform these files in object files. For example by typing BGIOBJ EGAVGA <ENTER> Then you get a file called EGAVGA.OBJ Do the same for the CHR files and get LITT.OBJ and TRIP.OBJ 3 - Copy these object files in the sub-directory where is GRAPHICS.LIB (usually TC\LIB\) 4 - Add the object files to the library with TLIB by typing TLIB GRAPHICS+ EGAVGA <ENTER> and so on for all the files. We had to do it file by file because TLIB did not want to deal with SANS.OBJ and we do not know why. Then all you have to do is to declare these drivers in the beginning of the program with 'registerbgidriver' and 'registerbgifont' (cf the program !). F - KNOWN PROBLEMS ------------------ All the source code was written in full ANSI-C compatible code except one function '_setcursortype()' which is provided in the graphics.h library file of some compilers. This function is not in the TurboC version 1 to 2. You have to build your own function to hide and show the cursor. This is the code. All you have to do is to replace the '_setcursortype(_NOCURSOR);' by a call to the function 'hidecursor()' and '_setcursortype(_NORMALCURSOR)'; by a call to the function 'showcursor()'. Of course, you will need to add these function to one of the source file before compiling. void hidecursor(void) { union REGS regs; regs.h.al=0x01; regs.h.ch=32; regs.h.cl=14; int86(0x0010,®s,®s); /* hide blinking text cursor */ } void showcursor(void) { union REGS regs; regs.h.ah=0x01; regs.h.ch=1; regs.h.cl=14; int86(0x0010,®s,®s); /* restore (show) text cursor */ } This is just a call to the interrupt 0x10. To understand more about interrupts, see the following chapter 'How to handle the mouse'. If you find other problems, please contact us, so we can fix them. G - BONUS : HOW TO HANDLE THE MOUSE ----------------------------------- To handle the mouse we use the interrupt 0x33. An interrupt is a routine that allows you to communicate directly with the processor, either via DOS or via BIOS. As its name tells it, you ask the computer to stop its current work to do a specific task. To do this you put in little processor memories, called registers, some numbers that are the code of what you want to do and then you call the interrupt. Thus the processor looks at the data codes, do the instruction and, if required, returns information by putting them in registers where you can get them (for instance the cursor position). If you work in assembly language, you need to save the content of the registers in the stack and, when you have finished, put back in every registers what was in it. Otherwise you can get errors or even crash your program. If you use the provided functions of your C compiler, you do not have to care about all this. All is done by the compiler. There are several types of registers : - General registers (AX,BX,CX,DX) which are composed of 16 bits that you can access in once (AX for instance) or two bytes. In this case, we speak of AH (High byte, bits 7 to 15) and AL (low byte, bits 0 to 7). The access is different. If you want to enter just one byte, for example to reset AL register to 0 you write inreg.h.al=0x00; The content of AH will not be modified. On the other hand, if you write inreg.x.ax=0x00; you will put the whole AX register to 0 (same as 0x0000). - Other 16 bits general registers (SP,BP,SI,DI). - 16 bits segmentation registers (CS,DS,SS,ES,IP) - State and control register. To handle the mouse, you will just use the first 4. Interrupt 0x33, functions ------------------------- Let's see how to use it to control the mouse. To avoid doing an error, we put the data code in hexadecimal. Test whether the mouse is here ------------------------------ Input AX = 0x00 Output AX = 0 No mouse or no driver loaded AX = -1 Mouse BX = number of buttons Set mouse cursor on ------------------- Input AX = 0x01 Output Hide mouse cursor ----------------- Input AX = 0x02 Output Get mouse position and buttons state ------------------------------------ Input AX = 0x03 Output BX = buttons state 1 = left button pressed 2 = right button pressed 3 = right and left buttons pressed 4 = middle button pressed CX = column (x) in pixels DX = line (y) in pixels Put the mouse in (x,y) ---------------------- Input AX = 0x04 BX = column (x) CX = line (y) Output Get the number of times the button was pressed ---------------------------------------------- Input AX = 0x05 BX = button to check (cf function 0x03) Output AX = buttons status BX = Number of press since the last call CX = column (x) at the last press DX = line (y) at the last press Notice that the counter is reset to 0 each time you call this function Get the number of times the button was released ----------------------------------------------- Input AX = 0x06 BX = button to check (cf function 0x03) Output AX = buttons status BX = Number of releases since the last call CX = column (x) at the last release DX = line (y) at the last release Notice that the counter is reset to 0 each time you call this function Change of the horizontal limits ------------------------------- Input AX = 0x07 BX = Left mouse limit (column in pixels) CX = Right mouse limit (column in pixels) Output Change of the vertical limits ----------------------------- Input AX = 0x08 BX = Top mouse limit (column in pixels) CX = Bottom mouse limit (column in pixels) Use the function 7 and the function 8 to define a window where to limit the mouse. The registered version of CPP includes the function 9 that allows you to redefine the mouse shape in graphic mode. It is provided with a lot of common mouse shapes such as various Arrows, Pointing Hand, ...